计划的 MQTT 控制

提示

计划的 MQTT 控制用于提前发送计划消息。有关实时控制，请参见实时 MQTT 控制。

本指南将帮助您在您的 Sofar EMS 上配置 MQTT，以远程控制和监控电池和太阳能电池板的安装。

你需要的

具有互联网连接的 Sofar EMS。
MQTT凭据：可以通过发送电子邮件至 support@eniris.be 来请求。
Python 开发环境（或任何其他 MQTT 客户端）。本指南使用用 Python 编写的基本示例来帮助您开始使用 MQTT 和发送命令。虽然我们推荐使用 Python 以便于使用，但任何其他 MQTT 客户端也是支持的。

附加信息

MQTT 是一种快速的互联网通信协议。它是一个发布/订阅消息系统，允许您的机器与 Sofar EMS 之间进行直接连接。您的资产被分类为太阳能、电池、EV 和 HVAC 组。目前，这种集成允许按组进行控制，而不是按设备。

第一次配置（新用户的起点）

我有一个 Sofar EMS，我希望为 MQTT 远程控制进行设置。

1. 检查您的网络

确保您的网络允许通过端口 1883 发送 mqtt 网络流量。您可以使用以下命令进行检查：

nc -zv mqtt.eniris.be 1883

如果此命令不可用，您可以选择下载并执行这个 Python 代码。

在出现疑问时，请咨询您的网络工程师或在发生连接错误时暂时使用您手机的 4G/5G 热点。

备注

当您网络无法访问端口 1883 时，我们提供了端口 80 的备份。您可以在本手册的后面步骤中在您的 MQTT 客户端进行配置。

2. 添加您的设备

登录到调试界面并确保设备已添加到 Sofar EMS。

3. 添加 MQTT 外部信号

4. 启用 MQTT 远程信号

选择您希望包含在 MQTT 远程控制中的所有设备。

5. 远程信号已添加

MQTT 远程控制界面现在已在 Sofar EMS 上激活。

我们现在准备使用简单示例发送一些基本命令。状态列告诉您是否有任何命令处于活动状态。

Python 演示脚本

一个好的起点是用一个简单的示例来测试您新设置的集成。

此测试代码简单地持续发送以下计划：

电池：在 10 分钟内以 5 kW 的功率充电 15 分钟
太阳能：在 30 分钟内将功率设置为 0 kW 持续一小时

Sofar EMS 会返回一条包含唯一计划标识符的确认消息，或一条错误消息。

然后，我们获取两种设备类型的下一个计划，以确认命令成功。

请在您喜欢的 Python IDE 中下载下面的文件。填写您的序列号和 MQTT 凭据并执行脚本：

当上述操作成功时，您可以继续发送其他类型的消息。所有消息将在下面描述。

发送命令的 MQTT 文档

本节详细说明设置 Sofar EMS 网络内设备的计划控制所需的 MQTT 消息格式和有效负载要求。

MQTT 主题

订阅主题：standard1/rp_one_s/remoteScheduleMetrics/<controller SN>
反馈主题：standard1/outbound/remoteScheduleMetrics/feedback/<controller SN>

其中 <controller SN> 应替换为您打算控制的 Sofar EMS 的实际序列号。

MQTT 消息类型

1. 设置计划 (`set_schedule`)

为设备类型创建新的计划。

{
    "extraTags": {
        "nodeId": "<Controller SN>_site_0"
    },
    "time": <Unix 时间戳>,
    "message_type": "set_schedule",
    "fields": {
        "device_type": "<设备类型>",
        "node_id": "<节点 ID>"（可选），
        "start_time": <Unix 时间戳>,
        "end_time": <Unix 时间戳>,
        "policy": "<策略>",
        "power_setpoint_w": <功率设定值（瓦特）>,
        "replace_overlap": <True/False>（可选）（默认=False）
    }
}

响应（成功）：

{
    "requestTime": <Unix 时间戳>,
    "time": <Unix 时间戳>,
    "siteNodeId": "<Controller SN>_site_0",
    "data": {
        "message_type": "set_schedule_ack",
        "state": {
            "schedule_id": <计划 ID>,
            "deleted_ids": <如果 replace_overlap=True 则删除的计划 ID>
        },
        "responseCode": 0
    }
}

2. 获取计划 (`get_schedule`)

通过 ID 检索特定计划。

{
    "extraTags": {
        "nodeId": "<Controller SN>_site_0"
    },
    "time": <Unix 时间戳>,
    "message_type": "get_schedule",
    "fields": {
        "id": <计划 ID>
    }
}

响应：

{
    "requestTime": <Unix 时间戳>,
    "time": <Unix 时间戳>,
    "siteNodeId": "<Controller SN>_site_0",
    "data": {
        "message_type": "get_schedule_ack",
        "state": <计划>,
        "responseCode": 0
    }
}

3. 获取当前活动计划 (`get_active_schedule`)

检索设备类型的当前活动计划。

{
    "extraTags": {
        "nodeId": "<Controller SN>_site_0"
    },
    "time": <Unix 时间戳>,
    "message_type": "get_active_schedule",
    "fields": {
        "device_type": "<设备类型>",
        "node_id": "<节点 ID>"（可选）
    }
}

响应（成功）：

{
    "requestTime": <Unix 时间戳>,
    "time": <Unix 时间戳>,
    "siteNodeId": "<Controller SN>_site_0",
    "data": {
        "message_type": "get_active_schedule_ack",
        "state": <计划>,
        "responseCode": 0
    }
}

4. 获取下一个计划 (`get_next_schedule`)

检索设备类型的下一个即将到来的计划。

{
    "extraTags": {
        "nodeId": "<Controller SN>_site_0"
    },
    "time": <Unix 时间戳>,
    "message_type": "get_next_schedule",
    "fields": {
        "device_type": "<设备类型>",
        "node_id": "<节点 ID>"（可选）
    }
}

响应（成功）：

{
    "requestTime": <Unix 时间戳>,
    "time": <Unix 时间戳>,
    "siteNodeId": "<Controller SN>_site_0",
    "data": {
        "message_type": "get_next_schedule_ack",
        "state": <计划>,
        "responseCode": 0
    }
}

5. 获取计划列表 (`get_schedules`)

检索特定日期的所有计划。

{
    "extraTags": {
        "nodeId": "<Controller SN>_site_0"
    },
    "time": <Unix 时间戳>,
    "message_type": "get_schedules",
    "fields": {
        "date": "<日期字符串格式 dd/mm/yyyy>"
    }
}

Response (成功):

{
    "requestTime": <Unix Timestamp>,
    "time": <Unix Timestamp>,
    "siteNodeId": "<Controller SN>_site_0",
    "data": {
        "message_type": "get_schedules_ack",
        "state": {
            "schedules": [<Schedule>, ...]
        },
        "responseCode": 0
    }
}

6. 获取未来时间表 (`get_future_schedules`)

检索所有未来时间表。

{
    "extraTags": {
        "nodeId": "<Controller SN>_site_0"
    },
    "time": <Unix Timestamp>,
    "message_type": "get_future_schedules",
    "fields": {}
}

Response (成功):

{
    "requestTime": <Unix Timestamp>,
    "time": <Unix Timestamp>,
    "siteNodeId": "<Controller SN>_site_0",
    "data": {
        "message_type": "get_future_schedules_ack",
        "state": {
            "schedules": [<Schedule>, ...]
        },
        "responseCode": 0
    }
}

7. 删除时间表 (`remove_schedule`)

通过 ID 删除特定时间表。

{
    "extraTags": {
        "nodeId": "<Controller SN>_site_0"
    },
    "time": <Unix Timestamp>,
    "message_type": "remove_schedule",
    "fields": {
        "id": <Schedule ID>
    }
}

Response (成功):

{
    "requestTime": <Unix Timestamp>,
    "time": <Unix Timestamp>,
    "siteNodeId": "<Controller SN>_site_0",
    "data": {
        "message_type": "remove_schedule_ack",
        "state": "时间表 <Schedule ID> 已成功删除",
        "responseCode": 0
    }
}

8. 获取站点反馈 (`get_feedback`)

检索系统状态的详细反馈。

{
    "extraTags": {
        "nodeId": "<Controller SN>_site_0"
    },
    "time": <Unix Timestamp>,
    "message_type": "get_feedback",
    "fields": {}
}

Response (成功):

反馈有效载荷结构

标准时间表响应格式

{
    "id": <Schedule ID>,
    "device_type": "<Device Type>",
    "node_id": "<Node ID>" (可选),
    "start_time": <Unix Timestamp>,
    "end_time": <Unix Timestamp>,
    "policy": "<Schedule Policy>",
    "power_setpoint_w": <Setpoint in watts>,
    "created_at": <Unix Timestamp>
}

组件类型和策略

有关可调度的可用组件和策略的详细信息，请参阅实时 MQTT 控制文档中的 MQTT 组件和策略部分。

可以使用可选的 node_id 字段发送特定于设备的时间表，该字段指的是可控设备的节点 ID。

错误处理

当发生错误时，所有消息都可以返回错误响应，responseCode: 1：

{
    "requestTime": <Unix Timestamp>,
    "time": <Unix Timestamp>,
    "siteNodeId": "<Controller SN>_site_0",
    "data": {
        "message_type": "<Message Type>_ack",
        "error": <Error Body>,
        "responseCode": 1
    }
}

当发生无关错误时，消息类型将是 (general_error)。

常见错误包括：

与现有时间表重叠
无效的时间范围
找不到设备类型
找不到时间表 ID
对于设备类型无效的策略

时间表管理规则

重叠规则
- 同一设备类型的时间表不能重叠
- 同一设备的时间表不能重叠
- 同一设备和设备类型的时间表不能重叠
- 如果在创建新时间表时将 replace_overlap 变量设置为 True，则会删除现有的重叠时间表。
每个时间表必须具备：
- 有效的设备类型
- 开始时间（Unix 时间戳）
- 结束时间（Unix 时间戳）
- 策略（与设备类型可用的策略相匹配）
- 功率设定值（对于需要的策略）
开始时间必须在结束时间之前
开始时间必须至少为五分钟后
只有当时间表开始至少在五分钟后时，才能删除时间表
时间表可以独立设置为不同的设备类型
当时间表激活时，系统会自动应用适当的策略

你需要的​

附加信息​

第一次配置（新用户的起点）​

1. 检查您的网络​

2. 添加您的设备​

3. 添加 MQTT 外部信号​

4. 启用 MQTT 远程信号​

5. 远程信号已添加​

Python 演示脚本​

发送命令的 MQTT 文档​

MQTT 主题​

MQTT 消息类型​

1. 设置计划 (set_schedule)​

2. 获取计划 (get_schedule)​

3. 获取当前活动计划 (get_active_schedule)​

4. 获取下一个计划 (get_next_schedule)​

5. 获取计划列表 (get_schedules)​

6. 获取未来时间表 (get_future_schedules)​

7. 删除时间表 (remove_schedule)​

8. 获取站点反馈 (get_feedback)​

标准时间表响应格式​

组件类型和策略​

错误处理​

时间表管理规则​

你需要的

附加信息

第一次配置（新用户的起点）

1. 检查您的网络

2. 添加您的设备

3. 添加 MQTT 外部信号

4. 启用 MQTT 远程信号

5. 远程信号已添加

Python 演示脚本

发送命令的 MQTT 文档

MQTT 主题

MQTT 消息类型

1. 设置计划 (`set_schedule`)

2. 获取计划 (`get_schedule`)

3. 获取当前活动计划 (`get_active_schedule`)

4. 获取下一个计划 (`get_next_schedule`)

5. 获取计划列表 (`get_schedules`)

6. 获取未来时间表 (`get_future_schedules`)

7. 删除时间表 (`remove_schedule`)

8. 获取站点反馈 (`get_feedback`)

标准时间表响应格式

组件类型和策略

错误处理

时间表管理规则